The ODF FW_CExtensionManager class provides support for the registration, creation, and management of subclasses of ODExtension. This document describes the steps required to implement extension support in your part.
Enabling Extension Support
Extension management can be enabled in an ODF part by editing its “Defines.k” file. In its default state, “Defines.k” contains the following line:
#define FW_SUPPORTS_EXTENSIONS 0
To enable extension management, edit the line to read:
#define FW_SUPPORTS_EXTENSIONS 1
Building a part with FW_SUPPORTS_EXTENSIONS defined as 1 causes ODF to automatically instantiate an instance of FW_CExtensionManager when your part is initialized.
Accessing the Extension Manager
Your part’s extension manager can be accessed by calling the GetExtensionManager of FW_CPart as in the following function, SomeMethod, that takes an environment and a pointer to a part as parameters:
void SomeMethod(Environment* ev, CMyPart* myPart)
{
FW_CExtensionManager* extMgr;
extMgr = myPart->GetExtensionManager(ev);
}
ODObject Extension API
ODObject and derived classes have a small API for extension-related arbitration. The API consists of three methods: HasExtension, AcquireExtension, and ReleaseExtension. ODF provides support for this API at the part level. ODF does not provide support for this API for objects other than parts.
Registering An Extension
Extensions supported by your part need to be registered with the extension manager. To register your extension, first obtain your part’s extension manager. Once you’ve obtained the extension manager, call the RegisterExtension method of the extension manager. The parameters passed to RegisterExtension are detailed below:
const char* name : extensions are acquired by name. This should be a pointer to a constant or to a string allocated in the heap that exists while your part is active. It should not be a pointer to a temporary object created on the stack.
CreateExtensionFunc createFunc : The address of the creation function to call when the extension is requested by name. The creation function must be of the following type:
void* refCon : This parameter will be passed to the creation function registered for the extension. You can use this to store a value you need access to when creating your extension.
FW_Boolean cacheWhenRelease : When all clients of your extension have released the extension, the extension manager will either dispose the extension or cache it, depending on this value. If cacheWhenReleased is FALSE, the extension will be disposed when the last client releases the extension. The creation function will be called the next time the extension is acquired. If cacheWhenReleased is TRUE, the extension manager will keep the extension cached when the last client releases it.
Note: When OpenDoc gets low on memory it calls the Purge method of active parts. When an ODF part’s Purge method is called, it purges cached extensions to free memory. This means that your part cannot rely on caching to always keep an instance of a specific extension alive. If you require this behavior, you should explicitly acquire a reference to the extension to prevent its reference count from dropping to zero.
Testing for an Extension
When OpenDoc or an OpenDoc object wants to test whether or not a part can provide a specific extension, it calls the object’s HasExtension method. When your part’s HasExtension method is called, the extension manager will return TRUE if the specified extension has been registered, and FALSE if it has not.
Acquiring an Extension
When OpenDoc or an OpenDoc object wants to acquire an extension, it calls the object’s AcquireExtension method. The ODObject API of AcquireExtension is as follows (this interface is defined by OpenDoc, not by ODF) :
When your part’s AcquireExtension method is called from outside of your part (i.e., by OpenDoc or another part), ODF automatically provides a createIt value of TRUE. At times, it may be necessary for your part to acquire one of its own extensions to get or set data owned by the extension. In this case, it makes sense to only acquire the extension if it already exists. Passing a createIt value of FALSE will acquire the extension if it exists, but will not allow it to be created if it does not.
When your part’s AcquireExtension method is called, the extension manager will do the following:
1. If an extension of the specified name already exists, the extension’s Acquire method will be called to increment its reference count, and the extension will be returned to the caller. This applies to cached extensions as well as extensions that exist and have a reference count greater than zero. This mechanism insures that your part will provide one, and only one, instance of a specific extension regardless of the number of clients.
2. If an extension of the specifed name does not exist, but the extension has been registered and the value of createIt is TRUE, the appropriate creation function will be called. The creation function is expected to create, initialize and return an instance of the specified extension. The extension manager returns the newly created extension to the caller.
3. If the extension does not exist and either has not been registered or the value of createIt is FALSE, the AcquireExtension method your part inherited from its base class is called, and the result is returned. In the current version of OpenDoc, calling ODPart::AcquireExtension causes an exception to be thrown, which is the correct behavior when an unsupported extension is acquired.
Releasing an Extension
When a client of an extension is finished using the extension, it calls the Release method of the extension. Note the semantics: an extension is acquired from its base object, but is released directly. When the extension reference count drops to zero, the extension calls the ReleaseExtension method of its base object.
When your part’s ReleaseExtension method is called, the extension manager does the following:
1. If the extension was created by the extension manager and should be cached when released, the extension manager caches the extension and returns.
2. If the extension was created by the extension manager and should not be cached when released, the extension manager deletes the extension and returns.
3. If the extension was not created by the extension manager, the ReleaseExtension method your part inherited from its base class is called. In the current version of OpenDoc, calling ODPart::ReleaseExtension causes an exception to be thrown, which is the correct behavior when an unknown extension is released.
Purging Extensions
When OpenDoc gets low on memory, it calls the Purge method of active parts. When an ODF part’s Purge method is called, ODF calls the PurgeCachedExtensions method of the FW_CExtensionManager associated with the part. PurgeCachedExtensions deletes all extensions cached by the extension manager.
Abandoning Extensions
When a base object is deleted, it is the responsibility of the base object to call the BaseRemoved method of every extension the object has created. ODF implements this for parts by calling the AbandonExtensions method of FW_CExtensionsManager when the part’s ReleaseAll method is called. AbandonExtensions deletes all cached extensions and calls the BaseRemoved method of every existing extension that has a reference count greater than zero.
Implementing Extensions
The OpenDoc extension protocol is slightly complex. The following guidelines provide useful information on the correct implementation of extensions. These tips are not specific to ODF.
Every method of an extension should call the IsValid method of the extension before referencing the extension’s base object. If IsValid returns FALSE, the extension should throw an error of type kODErrInvalidExtension. In ODF, this can be done as follows:
FW_PlatformError error;
if (somSelf->IsValid(ev))
{
error = DoSomething(ev);
}
else
error = kODErrInvalidExtension;
if (error != FW_xNoError)
FW_SetEvError(ev, error);
Every extension class must override Release and implement the following logic (this snippet is taken directly from the ODF Semantic Interface extension):
The extension MUST test IsValid before calling the inherited Release method. This is necessary because Release will decrement the reference count of the extension and, if the reference count drops to zero, will call the ReleaseExtension method of the base object. The base object may delete the extension when ReleaseExtension is called. It is not safe to call the IsValid method of the extension after it has been deleted. If IsValid is FALSE, the base object has been removed. If the base has been removed, and the reference count dropped to zero when the inherited Release method was called, the extension must delete itself. If the extension does not delete itself, a memory leak will result.
